lets_plot.geo_data.NamesGeocoder

class lets_plot.geo_data.NamesGeocoder(level: Optional[Union[str, lets_plot.geo_data.gis.request.LevelKind]] = None, request: Optional[Union[str, List[str], pandas.core.series.Series]] = None)

Do not use this class explicitly.

Instead you should construct its objects with special functions: geocode(), geocode_cities(), geocode_counties(), geocode_states(), geocode_countries(), reverse_geocode().

__init__(level: Optional[Union[str, lets_plot.geo_data.gis.request.LevelKind]] = None, request: Optional[Union[str, List[str], pandas.core.series.Series]] = None)

Initialize self.

scope(scope)lets_plot.geo_data.geocoder.NamesGeocoder

Limit area of interest to resolve an ambiguity.

Parameters

scope (str or Geocoder) – Area of interest. If it is of str type then it should be the geo-object name. If it is of Geocoder type then it must contain only one object.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

1
2
3
4
5
6
7
8
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
scope = geocode_states('Kentucky')
city = geocode_cities('Franklin').scope(scope).get_boundaries()
display(city)
ggplot() + geom_map(data=city) + ggtitle('Franklin, Kentucky')
The geodata is provided by © OpenStreetMap contributors and is made available here under the Open Database License (ODbL).
city found name geometry
0 Franklin Franklin MULTIPOLYGON (((-86.50721 36.72540, -86.50738 ...
highlights(v: bool)

Add matched string to geocodes DataFrame. Doesn’t affect GeoDataFrame.

Parameters

v (bool) – If True geocodes DataFrame will contain column ‘highlights’ with string that matched the name.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

1
2
from lets_plot.geo_data import *
geocode(names='OH').allow_ambiguous().highlights(True).get_geocodes()
id state found name highlights
0 324123 OH Ohio [OH, US-OH]
1 4559203 OH Omaheke Region [OH, NA-OH]
countries(countries)

Set parents for ‘country’ level to resolve an ambiguity or to join geometry with data via multi-key.

Parameters

countries (str or Geocoder or list) – Parents for ‘country’ level. If it is of str type then it should be the country name. If it is of Geocoder type then it must contain the same number of values as the number of names of Geocoder. If it is of list type then it must be the same size as the number of names of Geocoder.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

1
2
3
4
5
6
7
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
cities = geocode_cities(['Boston', 'Boston']).countries(['US', 'UK']).get_centroids()
display(cities)
ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)
city found name country geometry
0 Boston Boston US POINT (-71.08845 42.31104)
1 Boston Boston UK POINT (-0.04871 52.97437)
states(states)lets_plot.geo_data.geocoder.NamesGeocoder

Set parents for ‘state’ level to resolve an ambiguity or to join geometry with data via multi-key.

Parameters

states (str or Geocoder or list) – Parents for ‘state’ level. If it is of str type then it should be the state name. If it is of Geocoder type then it must contain the same number of values as the number of names of Geocoder. If it is of list type then it must be the same size as the number of names of Geocoder.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

1
2
3
4
5
6
7
8
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
states = geocode_states(['Massachusetts', 'New York'])
cities = geocode_cities(['Boston', 'Boston']).states(states).get_centroids()
display(cities)
ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)
city found name state geometry
0 Boston Boston Massachusetts POINT (-71.08845 42.31104)
1 Boston North Boston New York POINT (-78.77965 42.67952)
counties(counties: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, lets_plot.geo_data.geocoder.Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]])lets_plot.geo_data.geocoder.NamesGeocoder

Set parents for ‘county’ level to resolve an ambiguity or to join geometry with data via multi-key.

Parameters

counties (str or Geocoder or list) – Parents for ‘county’ level. If it is of str type then it should be the county name. If it is of Geocoder type then it must contain the same number of values as the number of names of Geocoder. If it is of list type then it must be the same size as the number of names of Geocoder.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

1
2
3
4
5
6
7
8
9
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
counties = geocode_counties(['Suffolk County', 'Erie County'])\
           .states(['Massachusetts', 'New York'])
cities = geocode_cities(['Boston', 'Boston']).counties(counties).get_centroids()
display(cities)
ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)
city found name county geometry
0 Boston Boston Suffolk County POINT (-71.08845 42.31104)
1 Boston North Boston Erie County POINT (-78.77965 42.67952)
ignore_not_found()lets_plot.geo_data.geocoder.NamesGeocoder

Remove not found objects from the result.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

1
2
3
4
5
6
7
8
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Hungary', 'Czechoslovakia'])\
            .ignore_not_found().get_boundaries(6)
display(countries)
ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')
country found name geometry
0 Germany Deutschland MULTIPOLYGON (((8.45947 47.59135, 8.48145 47.5...
1 Hungary Magyarország MULTIPOLYGON (((17.31445 45.98170, 17.29248 45...
ignore_all_errors()lets_plot.geo_data.geocoder.NamesGeocoder

Remove objects that have multiple matches from the result.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

1
2
3
4
5
6
7
8
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
cities = geocode_cities(['Boston', 'Worcester', 'Barnstable'])\
         .ignore_all_errors().get_centroids()
display(cities)
ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)
city found name geometry
0 Boston Boston POINT (-71.08845 42.31104)
1 Barnstable Barnstable POINT (-70.36277 41.66125)
allow_ambiguous()lets_plot.geo_data.geocoder.NamesGeocoder

For objects that have multiple matches add all of them to the result.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

1
2
3
4
5
6
7
8
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
cities = geocode_cities('Worcester').scope('US')\
         .allow_ambiguous().get_centroids()
display(cities)
ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)
city found name geometry
0 Worcester Worcester POINT (-71.81547 42.26787)
1 Worcester Worcester POINT (-72.57245 44.41330)
2 Worcester Worcester Township POINT (-75.34387 40.19262)
where(name: str, county: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]] = None, state: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]] = None, country: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]] = None, scope: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, shapely.geometry.Polygon]] = None, closest_to: Optional[Union[lets_plot.geo_data.geocodes.Geocodes, shapely.geometry.Point]] = None)NamesGeocoder

Allows to resolve ambiguity by setting up extra parameters. Combination of name, county, state, country identifies a row with an ambiguity. If row with given names does not exist error will be generated.

Parameters
  • name (str) – Name in Geocoder that needs better qualification.

  • county (str) – If Geocoder has parent counties this field must be present to identify a row for the name.

  • state (str) – If Geocoder has parent states this field must be present to identify a row for the name.

  • country (str) – If Geocoder has parent countries this field must be present to identify a row for the name.

  • scope (str or Geocoder or shapely.geometry.Polygon) – Limits area of geocoding. If parent country is set then error will be generated. If type is a str - geoobject should have geocoded scope in parents. If type is a Geocoder - geoobject should have geocoded scope in parents. Scope should contain only one entry. If type is a shapely.geometry.Polygon - geoobject centroid should fall into bbox of the polygon.

  • closest_to (Geocoder or shapely.geometry.Point) – Resolve ambiguity by taking closest geoobject.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

1
2
3
4
5
6
7
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
city = geocode_cities('Warwick').countries('US')                   .where(name='Warwick', country='US', scope='Massachusetts').get_centroids()
display(city)
ggplot() + geom_livemap() + geom_point(data=city, color='red', size=5)
city found name country geometry
0 Warwick Warwick US POINT (-72.33655 42.66792)

1
2
3
4
5
6
7
8
9
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
closest_city = geocode_cities('Birmingham').get_centroids().iloc[0].geometry
city = geocode_cities('Warwick')\
       .where(name='Warwick', closest_to=closest_city).get_centroids()
display(city)
ggplot() + geom_livemap() + geom_point(data=city, color='red', size=5)
city found name geometry
0 Warwick Warwick POINT (-1.58228 52.30154)
get_boundaries(resolution=None)GeoDataFrame

Return boundaries for given regions in the form of GeoDataFrame.

Parameters

resolution (int or str) – Boundaries resolution.

Returns

Table of data.

Return type

GeoDataFrame

Note

If resolution has int type, it may take one of the following values:

  • 1-3 for world scale view,

  • 4-6 for country scale view,

  • 7-9 for state scale view,

  • 10-12 for county scale view,

  • 13-15 for city scale view.

Here value 1 corresponds to maximum performance and 15 - to maximum quality.

If resolution is of str type, it may take one of the following values:

  • ‘world’ corresponds to int value 2,

  • ‘country’ corresponds to int value 5,

  • ‘state’ corresponds to int value 8,

  • ‘county’ corresponds to int value 11,

  • ‘city’ corresponds to int value 14.

Here value ‘world’ corresponds to maximum performance and ‘city’ - to maximum quality.

The resolution choice depends on the type of displayed area. The number of objects also matters: one state looks good on a ‘state’ scale while 50 states is a ‘country’ view.

It is allowed to use any resolution for all regions. For example, ‘city’ scale can be used for a state to get a more detailed boundary when zooming in, or ‘world’ for a small preview.

If resolution is not specified (or equal to None), it will be auto-detected. Auto-detection by level_kind is used for geocoding and the number of objects. In this case performance is preferred over quality. The pixelated geometries can be obtained. Use explicit resolution or inc_res() function for better quality.

If the number of objects is equal to n, then resolution will be the following:

  • For countries: if n < 3 then resolution=3, else resolution=1.

  • For states: if n < 3 then resolution=7, if n < 10 then resolution=4, else resolution=2.

  • For counties: if n < 5 then resolution=10, if n < 20 then resolution=8, else resolution=3.

  • For cities: if n < 5 then resolution=13, if n < 50 then resolution=4, else resolution=3.

Examples

1
2
3
4
5
6
7
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).inc_res().get_boundaries()
display(countries)
ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')
country found name geometry
0 Germany Deutschland MULTIPOLYGON (((7.47070 49.15297, 7.47070 49.1...
1 Poland Polska MULTIPOLYGON (((23.59863 51.89005, 23.64258 51...
get_centroids()GeoDataFrame

Return centroids (Point geometry) for given regions in form of GeoDataFrame.

Returns

Table of data.

Return type

GeoDataFrame

Examples

1
2
3
4
5
6
7
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).get_centroids()
display(countries)
ggplot() + geom_point(aes(color='found name'), data=countries, size=10)
country found name geometry
0 Germany Deutschland POINT (10.57925 51.16420)
1 Poland Polska POINT (19.15683 51.91905)
get_geocodes()DataFrame

Return metadata for given regions.

Returns

Table of data.

Return type

DataFrame

Examples

1
2
from lets_plot.geo_data import *
geocode_countries(['Germany', 'Russia']).get_geocodes()
id country found name
0 102955 Germany Deutschland
1 120379 Russia Россия
get_limits()GeoDataFrame

Return bboxes (Polygon geometry) for given regions in form of GeoDataFrame. For regions intersecting anti-meridian bbox will be divided into two parts and stored as two rows.

Returns

Table of data.

Return type

GeoDataFrame

Examples

1
2
3
4
5
6
7
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).get_limits()
display(countries)
ggplot() + geom_rect(aes(fill='found name'), data=countries, color='white')
country found name geometry
0 Germany Deutschland POLYGON ((15.04181 47.27011, 15.04181 55.05857...
1 Poland Polska POLYGON ((24.14578 49.00205, 24.14578 54.83565...
inc_res(delta=2)

Increase auto-detected resolution for boundaries.

Parameters

delta (int, default=2) – Value that will be added to auto-detected resolution.

Returns

Geocoder object specification.

Return type

Geocoder

Examples

1
2
3
4
5
6
7
from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).inc_res().get_boundaries()
display(countries)
ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')
country found name geometry
0 Germany Deutschland MULTIPOLYGON (((7.47070 49.15297, 7.47070 49.1...
1 Poland Polska MULTIPOLYGON (((23.59863 51.89005, 23.64258 51...